{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-spectrum/autocomplete';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/autocomplete/package.json';

```jsx import
import {SearchAutocomplete, Section, Item} from '@react-spectrum/autocomplete';
import {useFilter} from '@react-aria/i18n';
import Email from '@spectrum-icons/workflow/Email';
import Document from '@spectrum-icons/workflow/Document';
import WebPages from '@spectrum-icons/workflow/WebPages';
import SocialNetwork from '@spectrum-icons/workflow/SocialNetwork';
import ShoppingCart from '@spectrum-icons/workflow/ShoppingCart';
import Folder from '@spectrum-icons/workflow/Folder';
import {Text} from '@react-spectrum/text';
import {Avatar} from "@react-spectrum/avatar";
```

---
category: Pickers
keywords: [search field, input]
after_version: 3.0.0
---

# SearchAutocomplete

<PageDescription>{docs.exports.SearchAutocomplete.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['SearchAutocomplete', 'Section', 'Item']} />

## Example

```tsx example
<SearchAutocomplete label="Search with Autocomplete">
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```

## Content
SearchAutocomplete follows the [Collection Components](collections.html) API, accepting both static and dynamic collections.
Similar to [ComboBox](ComboBox.html), SearchAutocomplete accepts `<Item>` elements as children, each with a `key` prop. Basic usage of SearchAutocomplete, seen in the example above, shows multiple options populated with a string.
Static collections, as in this example, can be used when the full list of options is known ahead of time.

Dynamic collections, as shown below, can be used when the options come from an external data source such as an API call, or update over time.
Providing the data in this way allows SearchAutocomplete to automatically cache the rendering of each item, which dramatically improves performance.

As seen below, an iterable list of options is passed to the SearchAutocomplete using the `defaultItems` prop.

```tsx example
function Example() {
  let options = [
    {id: 1, name: 'Aerospace'},
    {id: 2, name: 'Mechanical'},
    {id: 3, name: 'Civil'},
    {id: 4, name: 'Biomedical'},
    {id: 5, name: 'Nuclear'},
    {id: 6, name: 'Industrial'},
    {id: 7, name: 'Chemical'},
    {id: 8, name: 'Agricultural'},
    {id: 9, name: 'Electrical'}
  ];

  return (
    <SearchAutocomplete
      label="Search engineering majors"
      defaultItems={options}>
      {item => <Item>{item.name}</Item>}
    </SearchAutocomplete>
  );
}
```

Alternatively, passing your list of options to SearchAutocomplete's `items` prop will cause the list of items to be controlled, useful for when you want to provide your own
filtering logic. See the [Custom Filtering](#custom-filtering) section for more detail.

### Internationalization
To internationalize a SearchAutocomplete, a localized string should be passed to the `children` of each `Item`.
For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the SearchAutocomplete is automatically flipped.

## Labeling
SearchAutocomplete can be labeled using the `label` prop. If the SearchAutocomplete is a required field, the `isRequired` and `necessityIndicator` props can be used to show a required state.

```tsx example
<SearchAutocomplete label="Favorite Animal" isRequired necessityIndicator="icon">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```
```tsx example
<SearchAutocomplete label="Favorite Animal" isRequired necessityIndicator="label">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```
```tsx example
<SearchAutocomplete label="Favorite Animal" necessityIndicator="label">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```

### Accessibility

If a visible label isn't specified, an `aria-label` must be provided to the SearchAutocomplete for
accessibility. If the field is labeled by a separate element, an `aria-labelledby` prop must be provided using
the `id` of the labeling element instead.

### Internationalization

In order to internationalize a SearchAutocomplete, a localized string should be passed to the `label` or `aria-label` prop.
When the `necessityIndicator` prop is set to `"label"`, a localized string will be provided for `"(required)"` or `"(optional)"` automatically.

## Links

By default, interacting with an item in a SearchAutocomplete updates the input value. Alternatively, items may be links to another page or website. This can be achieved by passing the `href` prop to the `<Item>` component. Interacting with link items navigates to the provided URL and does not update the input value.

```tsx example
<SearchAutocomplete label="Tech company websites">
  <Item href="https://adobe.com/" target="_blank">Adobe</Item>
  <Item href="https://apple.com/" target="_blank">Apple</Item>
  <Item href="https://google.com/" target="_blank">Google</Item>
  <Item href="https://microsoft.com/" target="_blank">Microsoft</Item>
</SearchAutocomplete>
```

### Client side routing

The `<Item>` component works with frameworks and client side routers like [Next.js](https://nextjs.org/) and [React Router](https://reactrouter.com/en/main). As with other React Spectrum components that support links, this works via the [Provider](Provider.html) component at the root of your app. See the [client side routing guide](routing.html) to learn how to set this up.

## Sections
SearchAutocomplete supports sections in order to group options. Sections can be used by wrapping groups of items in a `Section` element. Each `Section` takes a `title` and `key` prop.

### Static items
```tsx example
<SearchAutocomplete label="Preferred fruit or vegetable">
  <Section title="Fruit">
    <Item key="Apple">Apple</Item>
    <Item key="Banana">Banana</Item>
    <Item key="Orange">Orange</Item>
    <Item key="Honeydew">Honeydew</Item>
    <Item key="Grapes">Grapes</Item>
    <Item key="Watermelon">Watermelon</Item>
    <Item key="Cantaloupe">Cantaloupe</Item>
    <Item key="Pear">Pear</Item>
  </Section>
  <Section title="Vegetable">
    <Item key="Cabbage">Cabbage</Item>
    <Item key="Broccoli">Broccoli</Item>
    <Item key="Carrots">Carrots</Item>
    <Item key="Lettuce">Lettuce</Item>
    <Item key="Spinach">Spinach</Item>
    <Item key="Bok Choy">Bok Choy</Item>
    <Item key="Cauliflower">Cauliflower</Item>
    <Item key="Potatoes">Potatoes</Item>
  </Section>
</SearchAutocomplete>
```

### Dynamic items
Sections used with dynamic items are populated from a hierarchical data structure. Please note that `Section` takes an array of data using the `items` prop only.

```tsx example
function Example() {
  let options = [
    {name: 'Fruit', children: [
      {name: 'Apple'},
      {name: 'Banana'},
      {name: 'Orange'},
      {name: 'Honeydew'},
      {name: 'Grapes'},
      {name: 'Watermelon'},
      {name: 'Cantaloupe'},
      {name: 'Pear'}
    ]},
    {name: 'Vegetable', children: [
      {name: 'Cabbage'},
      {name: 'Broccoli'},
      {name: 'Carrots'},
      {name: 'Lettuce'},
      {name: 'Spinach'},
      {name: 'Bok Choy'},
      {name: 'Cauliflower'},
      {name: 'Potatoes'}
    ]}
  ];

  return (
    <SearchAutocomplete label="Preferred fruit or vegetable" defaultItems={options}>
      {item => (
        <Section key={item.name} items={item.children} title={item.name}>
          {item => <Item key={item.name}>{item.name}</Item>}
        </Section>
      )}
    </SearchAutocomplete>
  );
}
```

## Complex items
Items within SearchAutocomplete also allow for additional content used to better communicate options. Icons, avatars, and descriptions can be added to the `children` of `Item` as shown in the example below.
If a description is added, the prop `slot="description"` must be used to distinguish the different `<Text>` elements.
See Icon's [labeling](workflow-icons.html#labeling) section and Avatar's [accessibility](Avatar.html#accessibility) section for more information on how to label these elements.

```tsx example
<SearchAutocomplete label="Search apps">
  <Section title="Productivity">
    <Item textValue="Mail">
      <Email size="S" />
      <Text>Mail</Text>
      <Text slot="description">Send and receive emails</Text>
    </Item>
    <Item textValue="File Explorer">
      <Folder size="S" />
      <Text>File Explorer</Text>
      <Text slot="description">Navigate directories and open files</Text>
    </Item>
    <Item textValue="Document Editor">
      <Document size="S" />
      <Text>Document Editor</Text>
      <Text slot="description">Edit documents</Text>
    </Item>
  </Section>
  <Section title="Internet">
    <Item textValue="Web Browser">
      <WebPages size="S" />
      <Text>Web Browser</Text>
      <Text slot="description">Browse the internet</Text>
    </Item>
    <Item textValue="Social Media">
      <SocialNetwork size="S" />
      <Text>Social Media</Text>
      <Text slot="description">Connect with friends</Text>
    </Item>
    <Item textValue="Shopping">
      <ShoppingCart size="S" />
      <Text>Shopping</Text>
      <Text slot="description">Shop online</Text>
    </Item>
  </Section>
</SearchAutocomplete>
```

### With avatars

```tsx example
<SearchAutocomplete label="Search users">
  <Item textValue="User 1">
    <Avatar src="https://i.imgur.com/kJOwAdv.png" />
    <Text>User 1</Text>
  </Item>
  <Item textValue="User 2">
    <Avatar src="https://i.imgur.com/kJOwAdv.png" />
    <Text>User 2</Text>
  </Item>
  <Item textValue="User 3">
    <Avatar src="https://i.imgur.com/kJOwAdv.png" />
    <Text>User 3</Text>
  </Item>
  <Item textValue="User 4">
    <Avatar src="https://i.imgur.com/kJOwAdv.png" />
    <Text>User 4</Text>
  </Item>
</SearchAutocomplete>
```

## Asynchronous loading

SearchAutocomplete supports loading data asynchronously, and will display a progress circle reflecting the current load state,
set by the `loadingState` prop. It also supports infinite scrolling to load more data on demand as the user scrolls, via the `onLoadMore` prop.

This example uses the [useAsyncList](react-aria:useAsyncList.html) hook to handle loading the data. See the docs for more information.

```tsx example
import {useAsyncList} from '@react-stately/data';

interface Character {
  name: string
}

function AsyncLoadingExample() {
  let list = useAsyncList<Character>({
    async load({signal, cursor, filterText}) {
      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      // If no cursor is available, then we're loading the first page,
      // filtering the results returned via a query string that
      // mirrors the SearchAutocomplete input text.
      // Otherwise, the cursor is the next URL to load,
      // as returned from the previous page.
      let res = await fetch(cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`, {signal});
      let json = await res.json();

      return {
        items: json.results,
        cursor: json.next
      };
    }
  });

  return (
    <SearchAutocomplete
      label="Star Wars Character Lookup"
      items={list.items}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}
      loadingState={list.loadingState}
      onLoadMore={list.loadMore}>
      {item => <Item key={item.name}>{item.name}</Item>}
    </SearchAutocomplete>
  );
}
```

## Validation

SearchAutocomplete supports the `isRequired` prop to ensure the user enters a value, as well as custom client and server-side validation. It can also be integrated with other form libraries. See the [Forms](../forms) guide to learn more.

When the [Form](Form.html) component has the `validationBehavior="native"` prop, validation errors block form submission and are displayed as help text automatically. Errors are displayed when the user blurs the search field or submits the form.

```tsx example
import {Form, ButtonGroup, Button} from '@adobe/react-spectrum';

<Form validationBehavior="native" maxWidth="size-3000">
  {/*- begin highlight -*/}
  <SearchAutocomplete label="Favorite animal" name="animal" isRequired>
  {/*- end highlight -*/}
    <Item>Aardvark</Item>
    <Item>Cat</Item>
    <Item>Dog</Item>
    <Item>Kangaroo</Item>
    <Item>Panda</Item>
    <Item>Snake</Item>
  </SearchAutocomplete>
  <ButtonGroup>
    <Button type="submit" variant="primary">Submit</Button>
    <Button type="reset" variant="secondary">Reset</Button>
  </ButtonGroup>
</Form>
```

By default, `SearchAutocomplete` displays default validation messages provided by the browser. See [Customizing error messages](forms.html#customizing-error-messages) in the Forms guide to learn how to provide your own custom errors.

## Custom Filtering
By default, SearchAutocomplete uses a string "contains" filtering strategy when deciding what items to display in the dropdown menu. This filtering strategy can be overwritten
by filtering the list of items yourself and passing the filtered list to the SearchAutocomplete via the `items` prop.

The example below uses a string "startsWith" filter function obtained from the `useFilter` hook to display items that start with the SearchAutocomplete's current input
value only. By using the `menuTrigger` returned by `onOpenChange`, it also handles displaying the entire option list regardless of the current filter value when the SearchAutocomplete menu is
opened via the trigger button or arrow keys. `menuTrigger` tells you if the menu was opened manually by the user ("manual"), by focusing the SearchAutocomplete ("focus"), or by
changes in the input field ("input"), allowing you to make updates to other controlled aspects of your SearchAutocomplete accordingly.

```tsx example
function Example() {
  let options = [
    {id: 1, email: 'fake@email.com'},
    {id: 2, email: 'anotherfake@email.com'},
    {id: 3, email: 'bob@email.com'},
    {id: 4, email: 'joe@email.com'},
    {id: 5, email: 'yourEmail@email.com'},
    {id: 6, email: 'valid@email.com'},
    {id: 7, email: 'spam@email.com'},
    {id: 8, email: 'newsletter@email.com'},
    {id: 9, email: 'subscribe@email.com'}
  ];

  let [showAll, setShowAll] = React.useState(false);
  let [filterValue, setFilterValue] = React.useState('');
  let {startsWith} = useFilter({sensitivity: 'base'});
  let filteredItems = React.useMemo(() => options.filter(item => startsWith(item.email, filterValue)), [options, filterValue]);

  return (
    <SearchAutocomplete
      onOpenChange={(isOpen, menuTrigger) => {
        // Show all items if menu is opened manually
        // i.e. by the arrow keys or trigger button
        if (menuTrigger === 'manual' && isOpen) {
          setShowAll(true);
        }
      }}
      width="size-3000"
      label="Search Email Addresses"
      items={showAll ? options : filteredItems}
      inputValue={filterValue}
      onInputChange={(value) => {
        setShowAll(false);
        setFilterValue(value);
      }}>
      {item => <Item>{item.email}</Item>}
    </SearchAutocomplete>
  );
}
```

## Trigger options
By default, the SearchAutocomplete's menu is opened when the user types into the input field ("input"). There are two other supported modes: one where the menu opens when the SearchAutocomplete is focused ("focus") and
the other where the menu only opens when the user clicks or taps on the SearchAutocomplete's field button ("manual"). These can be set by providing "focus" or "manual" to the `menuTrigger` prop.
Guidelines on when to use a specific mode can be found [here](https://spectrum.adobe.com/page/combo-box/#Menu-trigger). Note that the mobile SearchAutocomplete experience requires the end user to press the SearchAutocomplete button
to open the tray regardless of the `menuTrigger` setting.

```tsx example
<SearchAutocomplete label="Favorite Animal" menuTrigger="focus">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```
```tsx example
<SearchAutocomplete label="Favorite Animal" menuTrigger="manual">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```

## Props

<PropTable component={docs.exports.SearchAutocomplete} links={docs.links} />

## Visual options

### Label alignment and position

By default, the label is positioned above the SearchAutocomplete. The `labelPosition` prop can be used to position the label to the side.
The `labelAlign` prop can be used to align the label as "start" or "end". For left-to-right (LTR) languages, "start" refers to the left most edge of the SearchAutocomplete and "end" refers to the right most edge.
For right-to-left (RTL) languages, this is flipped.

```tsx example
<SearchAutocomplete label="Favorite Animal" labelPosition="side" labelAlign="end">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```

### Quiet

```tsx example
<SearchAutocomplete label="Favorite Animal" isQuiet>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```

### Disabled

```tsx example
<SearchAutocomplete label="Favorite Animal" isDisabled>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```

### Read only

```tsx example
<SearchAutocomplete label="Search Animals" isReadOnly>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```

### Custom widths

```tsx example
<SearchAutocomplete label="Favorite Animal" width="size-6000" maxWidth="100%">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```

### Menu direction
```tsx example
<SearchAutocomplete label="Favorite Animal" direction="top">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
```

## Testing

The SearchAutocomplete features an overlay that transitions in and out of the page as it is opened and closed. Depending on
your device configuration, this overlay may render as a tray or a dropdown and the trigger itself may render as a button or a input. Additionally,
the SearchAutocomplete features automatic virtualization and may need specific mocks in a test environment to enable said virtualization properly.
Please see the following sections in the testing docs for more information on how to handle these
behaviors in your test suite.

[Timers](./testing.html#timers)

[Desktop vs Mobile](./testing.html#desktop-vs-mobile)

[Virtualized Components](./testing.html#virtualized-components)

[Long press](./testing.html#simulating-user-long-press)

Please also refer to [React Spectrum's test suite](https://github.com/adobe/react-spectrum/blob/main/packages/%40react-spectrum/autocomplete/test/SearchAutocomplete.test.js) if you find that the above
isn't sufficient when resolving issues in your own test cases.
